isp-status

Documents

isp-status → PRTG Integration Guide

Document: Operational contract mapping for PRTG\ Generated (UTC): 2026-02-18T16:42:44.427009Z

1. Overview

This document explains how to integrate PRTG Network Monitor with the isp-status API so that isp-status becomes a first-class component of your monitoring stack (not a standalone dashboard).

This is not a "how to install PRTG" guide. It focuses on:

  • Which isp-status endpoints matter to PRTG
  • How to map isp-status states into PRTG sensor states/channels
  • How to keep the integration stable over time

PRTG details and formats referenced here are based on Paessler's docs for Custom Sensors and REST Custom Sensors. citeturn0search0turn0search2turn0search1

2. Integration principles

2.1 What PRTG should treat as truth

PRTG should treat isp-status as the decision authority for uplink usability.

  • PRTG should not re-implement probe logic (ping/http) per uplink.
  • PRTG should consume the outcome (state) and optionally record supporting evidence.

This preserves your architecture: - isp-status = truth + evidence - PRTG = collection + alerting + reporting

2.2 The contract you monitor

The contract is intentionally narrow:

  • Primary contract: uplinks[].state from /api/status
  • Secondary contract (engine trust): /api/health ok
  • Optional: /api/history for SLA-style reporting (PRTG-specific reporting can come later)

3. What isp-status exposes (PRTG-relevant)

3.1 Real-time truth

  • GET /api/status\ Returns current uplink states and evidence inputs.

3.2 Monitoring integrity

  • GET /api/health\ Returns whether the monitoring engine is healthy enough to trust.

3.3 History (optional for PRTG later)

  • GET /api/history and GET /api/history.csv\ Provides structured rollups. Consider this reporting not alerting.

4. State mapping (isp-status → PRTG)

isp-status state codes:

isp-status code Meaning    Recommended PRTG meaning

              2 UP         OK / Green
              1 DEGRADED   Warning (Downstream impairment)
              0 DOWN       Down / Error

Important: /api/health ok=false means "monitoring engine is unhealthy".\ Treat that as: "data not trustworthy", not "uplinks down".

Recommended approach in PRTG: - Create a dedicated Engine Integrity sensor for /api/health - Create per-uplink sensors driven by /api/status

PRTG has multiple ways to ingest JSON. In practice, the most reliable approaches are:

Use a small script on the PRTG Probe host that: 1. Fetches http://isp-status/api/status 2. Extracts one uplink (or all) 3. Outputs PRTG "Advanced" format (XML or JSON)

Why this is recommended: - Avoids fragile JSONPath filtering on arrays - Handles name matching safely - Lets you provide one sensor per uplink with stable channels - Lets you hard-fail with proper PRTG error semantics

PRTG supports EXE/Script Advanced and defines output formats in its custom sensor docs. citeturn0search0

Option B: REST Custom Sensor (template mapping)

Use PRTG's REST Custom sensor that maps JSON via a .template file. citeturn0search2turn0search1

This works best when: - Your JSON fields are simple - You don't need complex filtering (arrays by name are awkward)

Reality check: /api/status returns an uplinks[] array. Mapping a specific entry by name is often easier with an adapter script (Option A).

6. Option A --- Script/EXE Advanced sensor (practical "operational contract")

6.1 Sensor design

Create one PRTG sensor per uplink with channels:

  • State (0/1/2)
  • Optional evidence channels:
    • Ping OK (count)
    • HTTP OK (count)
    • GW OK (0/1, or blank for NAT uplinks)

This makes PRTG dashboards and alerting clear: - Alert on State - Use evidence channels for diagnostics and trend graphs

6.2 Example script behavior

Inputs: - isp-status base URL (e.g., http://172.16.198.26:8080) - uplink name (exact match)

Output: - PRTG Advanced XML or JSON containing channels and values - On failure to reach API or parse: return PRTG error format

Paessler documents "advanced" custom sensor output formats under Custom Sensors. citeturn0search0

6.3 Example: Advanced XML output skeleton

This is a template example of what the script must output (PRTG reads this from stdout).

<prtg>
  <result>
    <channel>State</channel>
    <value>2</value>
  </result>
  <result>
    <channel>Ping OK</channel>
    <value>2</value>
  </result>
  <result>
    <channel>HTTP OK</channel>
    <value>3</value>
  </result>
  <text>Liquid (BGP01): up</text>
</prtg>

6.4 Example: Error output

Use PRTG's error convention so the sensor becomes Down/Error with a readable message:

<prtg>
  <error>1</error>
  <text>isp-status unreachable</text>
</prtg>

(See Paessler custom sensor docs for advanced formats and conventions.) citeturn0search0

6.5 Thresholds and alerting in PRTG

Recommended sensor settings:

  • State channel:
    • Error if value is 0
    • Warning if value is 1
    • OK if value is 2
  • Optional evidence channels:
    • Do not alarm directly; use them for context only

Note: PRTG can also map numeric states to text using lookups (optional), but the simplest operational contract is numeric + thresholds.

7. Option B --- REST Custom sensor (template mapping)

The REST Custom sensor queries an endpoint and maps JSON/XML fields using a .template mapping file. citeturn0search2turn0search1

When it's a good fit

  • You expose a dedicated per-uplink endpoint with stable fields (recommended if you choose REST templates)

When it's brittle

  • You need to filter uplinks[] by name inside /api/status.
    • Array filtering by name is usually where REST templates become fragile.

Recommendation if you want REST templates: create or expose a dedicated endpoint that returns one uplink only (stable keys, no arrays).

8. Monitoring integrity as a first-class sensor

Create one PRTG sensor that monitors /api/health.

Minimal check (conceptual): - OK if ok=true - Error if ok=false

Reason: - If the engine is unhealthy, uplink state may be stale or incomplete. - This prevents false confidence in "green" uplinks when the monitor is sick.

PRTG alerting should differentiate: - Network failure - Monitoring failure

9. Polling intervals and load

  • /api/status runs active probes and updates history.
  • Do not poll excessively.

Recommended: - 30s to 60s intervals per uplink sensor - Stagger sensors if possible (PRTG often naturally spreads checks)

If you later need higher frequency, treat that as a capacity decision (probe timeouts, CPU, bandwidth, etc.).

10. Naming, identity, and URL encoding

Uplink name is the identity used by history and is what operators recognize.

Tradeoff: - Human-readable, but includes spaces/parentheses.

10.2 URL encoding pitfall (real-world lesson)

When requesting endpoints that require name=... (history queries), always use URL encoding:

curl -G --data-urlencode "name=Liquid (BGP01)" ...

Avoid raw query strings with spaces/parentheses.

11. What "done" looks like (acceptance criteria)

PRTG integration is "operational" when:

  1. PRTG shows one sensor per uplink with a State channel.
  2. State transitions in PRTG match isp-status:
    • 2 → OK
    • 1 → Warning
    • 0 → Down
  3. PRTG has a separate Engine Integrity sensor based on /api/health.
  4. Alerting rules do not conflate monitoring failure with network failure.
  5. Dashboards show:
    • current state
    • trend context (optional evidence channels)

12. Next document (separate)

A dedicated PRTG Implementation Notes document will cover:

  • Exact sensor types chosen (EXE/Script Advanced vs REST Custom)
  • Where scripts/templates live on the probe
  • Exact PRTG UI steps and screenshots
  • Lookups, notification triggers, escalation policy

That is intentionally separate from this contract mapping guide.

13. Design principle

PRTG is not the truth engine.

  • isp-status is.
  • PRTG consumes and operationalizes that truth.